iOS SDK

概要

WebAR³ VPS のネイティブ iOS SDK は、ARKit を利用して VPS マップ内でユーザーをローカライズします。XCFramework 形式で提供され、UIKit／RealityKit／SwiftUI の各アプリで利用できます。Immersal スタイルに沿って、前提条件・インストール・権限設定・サービス初期化の順に解説します。

必要条件

iOS 12.0 以上
Swift 5 に対応した Xcode 12 以上
ARKit 対応デバイス（シミュレーターは非対応）

インストール方法

Swift Package Manager を使用

Xcode で File → Add Packages… を開きます。
https://github.com/WebAR-Studio/was-vps-ios.git を入力します。
任意のブランチまたはタグを選択し、ターゲットに追加します。

手動で組み込む

リポジトリをクローンします。

git clone https://github.com/WebAR-Studio/was-vps-ios.git

WASVPS.xcframework をプロジェクトにドラッグします。
General → Frameworks, Libraries, and Embedded Content でフレームワークが埋め込み済みか確認します。

権限を設定

カメラと位置情報の利用目的を Info.plist に追加して、システムの許可ダイアログを表示させます。

<key>NSCameraUsageDescription</key>
<string>AR コンテンツを表示するためにカメラへのアクセスが必要です。</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>正確な位置に AR コンテンツを配置するために位置情報が必要です。</string>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>VPSLocalization</key>
    <string>高精度のローカライズで AR 体験を安定させます。</string>
</dict>

VPS を初期化

VPSBuilder.initializeVPS で VPSService を生成します。ARSession、API キー、Location ID を渡してください。

APIキーが必要ですか？space.web-ar.studio で取得するか、support@webar3.com / support@web-ar.studio までメールしてください。

import ARKit
import WASVPS

final class VPSDemoController: UIViewController, ARSCNViewDelegate {
    @IBOutlet private weak var sceneView: ARSCNView!
    private var configuration: ARWorldTrackingConfiguration?
    private var vps: VPSService?

    override func viewDidLoad() {
        super.viewDidLoad()
        sceneView.delegate = self
        sceneView.scene = SCNScene()

        configuration = VPSBuilder.getDefaultConfiguration()

        VPSBuilder.initializeVPS(
            arSession: sceneView.session,
            apiKey: "your-api-key",
            locationIds: ["your-location-id"],
            url: "https://was-vps.web-ar.xyz/vps/api/v3",
            gpsUsage: false,
            delegate: self
        ) { service in
            self.vps = service
            self.vps?.start()
        }
    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        if let configuration { sceneView.session.run(configuration) }
    }

    func renderer(_ renderer: SCNSceneRenderer, updateAtTime time: TimeInterval) {
        vps?.frameUpdated()
    }
}

extension VPSDemoController: VPSServiceDelegate {
    func positionVPS(pos: ResponseVPSPhoto) {
        print("Localized pose:", pos)
    }

    func error(err: NSError) {
        print("VPS error:", err)
    }

    func sending(requestData: UploadVPSPhoto?) {
        print("Sending localization request…")
    }
}

sessionWasInterrupted でサービスを停止し、sessionInterruptionEnded で再開してください。

RealityKit での利用

RealityKit では ARSessionDelegate から毎フレーム frameUpdated() を呼び出します。

func session(_ session: ARSession, didUpdate frame: ARFrame) {
    vps?.frameUpdated()
}

ライフサイクルの呼び出し（start / stop / clearCustomLocPos）は SceneKit と同じです。

SwiftUI パターン

ARSCNView や ARView を UIViewRepresentable／UIViewControllerRepresentable でラップし、VPSService を ViewModel に保持して SwiftUI のボタンから start() / stop() を切り替えます。

追加オプション

setCustomLocPosForFirstRequest で初回リクエスト前に既知の姿勢を設定できます。
initializeVPS の url パラメーターで既定エンドポイント（https://was-vps.web-ar.xyz/vps/api/v3）を差し替え可能です。
gpsUsage を true にするとリクエストに端末の座標を添付します。

トラブルシューティング

VPSBuilder.getDefaultConfiguration() が nil を返す場合、その端末は ARKit に対応していません。
コールバックが届かないときは、毎フレーム frameUpdated() を呼んでいるか、API キーと Location ID が正しいか確認してください。
/examples フォルダに UIKit／RealityKit／SwiftUI の参考実装があります。

概要​

必要条件​

インストール方法​

Swift Package Manager を使用​

手動で組み込む​

権限を設定​

VPS を初期化​

RealityKit での利用​

SwiftUI パターン​

追加オプション​

トラブルシューティング​

概要